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ABOUT THIS CHAPTER 


This chapter describes the International Utilities Package, which enables you to 
make your Macintosh application country-independent. Routines are provided for 
formatting dates and times and comparing strings in a way that's appropriate to 
the country where your application is being used. There's also a routine for 
testing whether to use the metric system of measurement. These routines access 
country-dependent information (stored in a resource file) that also tells how to 
format numbers and currency; you can access this information yourself for your 
own routines that may require it. 


You should already be familiar with: 


* resources, as discussed in the Resource Manager chapter 
* packages in general, as described in the Package Manager chapter 
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ABOUT THE INTERNATIONAL UTILITIES PACKAGE 


Note: The extensions to the International Utilities Package described in this 
chapter were originally documented in Inside Macintosh, Volume V. As 
such, this information refers to the Macintosh SE and Macintosh II ROMs 
and System file version 4.1 and later. The sections of this chapter that 
cover these extensions are so noted. 


e*eClick on the X-Ref button, and refer to Technical Note #153.,¢ee 


The International Utilities Package has been extended to work in conjunction 
with the Script Manager. In addition, several new formatting options provide 
added flexibility in specifying exactly how dates and times are to be displayed. 
The string comparison capabilities have also been extended to handle non-Roman 
writing systems, such as Arabic and Japanese. 


Reader's guide: You need the information in this chapter if you are using one or 
more of the following in your application: 


* a non-Roman writing system 
« non-English date or time formats 
* routines that compare strings containing accented characters 
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INTERNATIONAL RESOURCES 


Country-dependent information is kept in the system resource file in two 
resources of type 'INTL', with the resource IDs 0 and 1: 


« International resource @ contains the formats for numbers, currency, 
and time, a short date format, and an indication of whether to use 
the metric system. 

e International resource 1 contains a longer format for dates (spelling 
out the month and possibly the day of the week, with or without 
abbreviation) and a routine for localizing string comparison. 


The system resource file released in each country contains the standard 
international resources for that country. Figure 1 illustrates the standard 
formats for the United States, Great Britain, Italy, Germany, and France. 


The routines in the International Utilities Package use the information in these 
resources; for example, the routines for formatting dates and times yield 
strings that look like those shown in Figure 1. Routines in other packages, in 
desk accessories, and in ROM also access the international resources when 
necessary, as should your own routines if they need such information. 


In some cases it may be appropriate to store either or both of the international 
resources in the application's or document's resource file, to override those in 
the system resource file. For example, suppose an application creates documents 
containing currency amounts and gets the currency format from international 
resource 0. Documents created by such an application should have their own copy 
of the international resource 0 that was used to create them, so that the unit 
of currency will be the same if the document is displayed on a Macintosh 
configured for another country. 


Information about the exact components and structure of each international 
resource follows here; you can skip this if you intend only to call the 
formatting routines in the International Utilities Package and won't access the 
resources directly yourself. 
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United Great 
Bates Britain Italy (erbany France 
Hum bers 1,234.56 1,234.56 1.234,56 1.2234,56 1 224.56 
List separator : P : : 4 
Cure y $0.23 £0.23 L. 0,23 0.23 DM 0,23 F 
(£0.45) (£0.45) L. 4,45 4,45 DMM 41,45 F 
$345.00 £345 L. 345 345,00 DET 325 F 
Time 9:05 AM 09:05 9:05 9:05 Uhr 9:05 
11:30 AM 11:30 11:30 11:30 Uhr 11:30 
11:20 PM 23:20 2s:2u 2o:20 Uhr 2s:20 
11:20:09 PIM 23:20:09 23:20:09 23:20:09 Uhr 2s720709 
Bhort date L2fzaies 22121985 22-12-1985 22.12.1985 22.12.85 
ariigs Oi2t1985 1-02-1985 1.02.1985 1.02.85 
Unabbrevisted Abbreviated 
Lome date United States Wednesday, February 1, 1985 Wed, Feb 1, 1985 
Great Britain Wednesday, February 1, 1955 Wed, Feb 1, 1955 
Italy mercoledi, 1 Febbraio 1935 mer, 1 Feb 1985 
GerbaLy Mittwoeh, 1. Februar 1985 Bt, 1. Feb 1985 
France Mercredi 1 fevrier 1985 Mer 1 fev 1955 


Figure 1-Standard International Formats 
Figure 1-Standard International Formats 


International Resource 0 


The International Utilities Package contains the following data types for 
accessing international resource 0: 


TYPE IntlOHndl = “*IntlOPtr; 

IntlOPtr = *IntlORec; 

IntlORec = PACKED RECORD 
decimalPt: CHAR; {decimal point character} 
thousSep: CHAR; {thousands separator} 
listSep: CHAR; {list separator} 
currsym1: CHAR; {currency symbol} 
currSym2: CHAR; 
currSym3: CHAR; 
currFmt: Byte; {currency format} 
dateOrder: Byte; {order of short date elements} 
shrtDateFmt: Byte; {short date format} 
dateSep: CHAR; {date separator} 
timeCycle: Byte; {0 if 24-hour cycle, 255 if 12-hour} 
timeFmt: Byte; {time format} 
mornStr: PACKED ARRAY[1..4] OF CHAR; 


{trailing string for first } 
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{ 12-hour cycle} 

eveStr: PACKED ARRAY[1..4] OF CHAR; 
{trailing string for last } 
{ 12-hour cycle} 


timeSep: CHAR; {time separator} 

timelSuff: CHAR; {trailing string for 24-hour cycle} 

time2Suff: CHAR; 

time3Suff: CHAR; 

time4Suff: CHAR; 

time5Suff: CHAR; 

time6Suf f: CHAR; 

time7Suff: CHAR; 

time8Suf f: CHAR; 

metricSys: Byte; {255 if metric, 0 if not} 

intlOVers: INTEGER {version information} 
END; 


Note: A NUL character (ASCII code 0) in a field of type CHAR means there's 
no such character. The currency symbol and the trailing string for 
the 24-hour cycle are separated into individual CHAR fields because 
of Pascal packing conventions. ALl strings include any required spaces. 


The decimalPt, thousSep, and listSep fields define the number format. The 
thousands separator is the character that separates every three digits to the 
left of the decimal point. The list separator is the character that separates 
numbers, aS when a list of numbers is entered by the user; it must be different 
from the decimal point character. If it's the same as the thousands separator, 
the user must not include the latter in entered numbers. 


CurrSyml through currSym3 define the currency symbol (only one character for the 
United States and Great Britain, but two for France and three for Italy and 
Germany). CurrFmt determines the rest of the currency format, as shown in Figure 
2. The decimal point character and thousands separator for currency are the same 
as in the number format. 


76 5 4 3 0 


Example of effect 


1 EF ewreney symbol leads, 0 if it trails 

1 EF minvs sign for negative, 0 if parentheses 
1 TE trailing decimal zeroes, 0 if pot 

1 FF leading integer zero, 0 if not 


Figure 2-—CurnrF mt Field 
Figure 2—CurrFmt Field 
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The following predefined constants are masks that can be used to set or test the 
bits in the currFmt field: 


CONST currSymLead = 16; {set if currency symbol leads} 
currNegSym = 32; {set if minus sign for negative} 
currTrailingZ = 64; {set if trailing decimal zeroes} 
currLeadingZ = 128; {set if leading integer zero} 


Note: You can also apply the currency format's leading- and 
trailing-zero indicators to the number format if desired. 


The dateOrder, shrtDateFmt, and dateSep fields define the short date format. 
DateOrder indicates the order of the day, month, and year, with one of the 
following values: 


CONST mdy = 0; {month day year} 
dmy = 1; {day month year} 
ymd = 2; {year month day} 


ShrtDateFmt determines whether to show leading zeroes in day and month numbers 
and whether to show the century, as illustrated in Figure 3. DateSep is the 
character that separates the different parts of the date. 


Poo 9 4 i] 


TT | 


: ee zero = day, teres 12t0ate5 12/2/85 
aling zero for mouth, wat Osis 131885 
1 F century ineluded, 0 if not 22.12.1985 | 22.12.85 


Ce [| 


Figure 3-ShitDateF mt Field 
Figure 3—-ShrtDateFmt Field 


To set or test the bits in the shrtDateFmt field, you can use the following 
predefined constants as masks: 


CONST dayLdingZ = 32; {set if leading zero for day} 
mntLdingZ = 64; {set if leading zero for month} 
century = 128; {set if century included} 


The next several fields define the time format: the cycle (12 or 24 hours); 
whether to show leading zeroes (timeFmt, as shown in Figure 4); a string to 
follow the time (two for 12-hour cycle, one for 24-hour); and the time separator 
character. 
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TTT ea | 


1 IE leading zero for seconds, 0 if mot 11-16-05 
1 EF leading zero for minutes, 0 if not 10-05 


1 IF leading zero for howrs, 0 if not 09:15 


Figure 4-TimeF mt Field 
Figure 4—TimeFmt Field 


The following masks are available for setting or testing bits in the timeFmt 
field: 


CONST secLeadingZ = 32; {set if leading zero for seconds} 
minLeadingZ = 64; {set if leading zero for minutes} 
hrLeadingZ = 128; {set it leading zero for hours} 


MetricSys indicates whether to use the metric system. The last field, intlOVers, 
contains a version number in its low-order byte and one of the following 
constants in its high-order byte: 


CONST verUS = 0; 
verFrance = 1; 
verBritain = 725 
verGermany = 3; 
verItaly = 4; 
verNetherlands = 5; 
verBelgiumLux = 6; 
verSweden ay 
verSpain = 8; 
verDenmark = 9; 
verPortugal = 10; 
verFrCanada = 11; 
verNorway = 12; 
verIsrael = 13; 
verJapan = 14; 
verAustralia = 15; 
verArabia = 16; 
verFinland = 17; 
verFrSwiss = 18; 
verGrSwiss = 19; 
verGreece = 20; 
vericeland = 21; 
verMalta = 22; 
verCyprus = 23; 
verTurkey = 24; 
verYugoslavia = 25; 


International Resource 1 
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The International Utilities Package contains the following data types for 
accessing international resource 1: 


TYPE IntllHndl = “Intl1Ptr; 
IntllPtr = *Intl1Rec; 
IntllRec = PACKED RECORD 
days: ARRAY[1..7] OF STRING[15]; {day names} 
months: ARRAY[1..12] OF STRING[15]; {month names} 
SuppressDay: Byte; {0 for day name, 255 for none} 
LngDateFmt: Byte; {order of long date elements} 
dayLeadingO: Byte; {255 for leading 0 in day number} 
abbrLen: Byte; {length for abbreviating names} 
std: PACKED ARRAY[1..4] OF CHAR; {strings } 
stl: PACKED ARRAY[1..4] OF CHAR; { for } 
st2: PACKED ARRAY[1..4] OF CHAR; { long } 
st3: PACKED ARRAY[1..4] OF CHAR; { date } 
st4: PACKED ARRAY[1..4] OF CHAR; { format} 
intllVers: INTEGER; {version information} 
localRtn: INTEGER {routine for localizing string } 
{ comparison; actually may be } 
{ longer than one integer} 
END; 


All fields except the last two determine the long date format. The day names in 
the days array are ordered from Sunday to Saturday. (The month names are of 
course ordered from January to December.) As shown below, the lngDateFmt field 
determines the order of the various parts of the date. StO0 through st4 are 
strings (usually punctuation) that appear in the date. 


LngDateFmt Long date format 
0 stO day name stl day st2 month st3 year st4 
255 stO0 day name stl month st2 day st3 year st4 


See Figure 5 for examples of how the International Utilities Package formats 
dates based on these fields. The examples assume that the suppressDay and 
dayLeading® fields contain 0. A suppressDay value of 255 causes the day name and 
stl to be omitted, and a dayLeading value of 255 causes a 0 to appear before day 
numbers less than 10. 


IngDateF mt stig stl sha st3 std Bad ple result 
a te ated = a ak Mittwoeh, 2. Februar 1989 
2a i Wednesday, February 1, 1989 


Figure 5—Long Date Formats 
Figure 5—Long Date Formats 


AbbrLen is the number of characters to which month and day names should be 
abbreviated when abbreviation is desired. 


The intllVers field contains version information with the same format as the 
intlOVers field of international resource 0. 
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LocalRtn contains a routine that localizes the built-in character ordering (as 
described below under "International String Comparison"). 
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CHANGES TO THE INTERNATIONAL RESOURCES 


Note: The extensions to the International Utilities Package described in this 
section were originally documented in Inside Macintosh, Volume V. As 
such, this information refers to the Macintosh SE and Macintosh II ROMs 
and System file version 4.1 and later. 


The 'INTL' resources with ID numbers 0 and 1 have been used in the past for 
international formats. The Script Manager now allows multiple formats to be 
used with the same system by adding multiple international script resources, as 
described in the Script Manager chapter. The new international resources are of 
types 'itlO', ‘itll', ‘itl2', ‘itlb', and ‘itlc'. Each installed script has an 
associated list of international resource numbers, generally in the range used 
for its fonts. For example, the Arabic script has the resources 'itl0', 

‘itll', and 'itl2' with numbers in the range $4600 to $47FF; the Roman script 
has the resources 'itlQ', ‘itll', and 'itl2' with numbers in the range $2 to 
$3FFF. 


In the default case, the resources used by the International Utilities package 
are determined by the script designated for the system font. However, you can 
force them to be determined by the font script (the script of the font in 
thePort), by clearing the IntlForce flag to 0. You can set and clear the 
IntlForce flag by using the SetEnvirons routine described in the Script Manager 
chapter. The selected resources will then be used internally by the 
International Utilities package. 


The 'itl@' and ‘itl1l' resources basically correspond to the former 'INTL' © and 
1; the 'itl2' resource contains new procedures for sorting, which are discussed 
below. The IUSetIntl call still uses the 'INTL' 0 and 1 resources. IUGetIntl, 
however, uses the 'itlO', ‘itll' and ‘'itl2' resources. 


For compatibility, the 'INTL' © and 1 resources are still present in the System 
file and remain the same; an 'INTL' 2 has been added to correspond to the 
'itl2'. Applications can access these resources by means of GetResource. 


Note: The one exception to the correspondence between an 'itlO' or ‘itll’ 
and 'INTL' © or 'INTL' 1 is that the lengths of the former may be 
increased at some future date: they are not guaranteed to remain 
the same length, although the positions of the existing fields will 
not change. 


The 'itlb' resource is a script bundle resource that determines which keyboard 
and which international formats are to be used. The ‘itlc' resource determines 
the system script. 


New Formatting Options 
New options are available for time cycle and dates. 


Time Cycle 
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A new constant value, zeroCycle, is provided for the timeCycle field in the 
Intl@Rec data structure to allow specification of 0:00 am/pm rather than 12:00 
or 24:00. 


Short Date Format 
Three new constant values, MYD, DYM, YDM, for the dateOrder field in the 


IntlORec data structure now allow the exact specification of the short date 
format, as follows: 


Constant Format 
MYD Month Year Day 
DYM Day Year Month 
YDM Year Day Month 


Long Date Format 


New values allow specification of the exact order of the elements in the long 
date format. If the byte value of the tngDateFmt field in the IntllRec data 
structure is neither 0 nor $FF, then its value is divided into four fields of 
two bits each. The least significant bit field (bits 0 and 1) corresponds to 
the first element in the long date format, while the most significant bit field 
(bits 6 and 7) specifies the last (fourth) element in the format. Four new 
constants (longDay, longWeek, lLongMonth, lLongYear) may be used to set each bit 
field to the appropriate value. 


For example, to specify the order day-of-week/day-of-month/month/year, you would 
set the value of lngDateFmt to: 


LongWeek*1 {sets bits 0 and 1 to longWeek} 
+ longDay*4 {sets bits 2 and 3 to longDay} 
+ LongMonth*16 {sets bits 4 and 5 to longMonth} 
+ longYear*64 {sets bits 6 and 7 to longYear} 


Suppress Day 


New values are available for the suppressDay field in the IntllRec data 
structure to enable suppression of any part of the date. If its value does not 
equal 0 or $FF, the field is treated as a bitmap. The values supDay, supWeek, 
supMonth and supYear may be used to set the appropriate bits in the suppressDay 
byte. For example, to suppress both the month and the year, the value of 
SuppressDay would be: supMonth + supYear. 


Using the International Resources 


Note: Before using any of the international resources, or using the Binary 
to Decimal routines, verify that the thePort and thePort*.txFont are 
set correctly, or that the intlForce flag is on. 


To make it easy to localize your application to different scripts and languages, 
use the international utilities for Date/Time/Number formatting. When formatting 
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numbers, use the fields in the international resources to find out the decimal, 
thousands or list separators for the given script. 


{Make sure the font is set properly in thePort, then} 


myHandle := intlOHndl(IUGetIntl(0)); {don't use GetResource! } 
myDecimal := myHandle**.decimalPt; {as in 1.234 in English} 
myThousands := myHandle**.thousSep; {as in 1,234,567 in English} 
myList := myHandle”™.listSep; fas in (3;4;5) in English} 


These three separators should always be distinct; they can be used for parsing. 
Programs that do not support input of numbers with thousands separators may want 
to override the list separator and use commas. The program should keep any 
overriding characters in a resource, so they can be changed if necessary. 

Before using the resource, it should first check to see that the decimal 
separator is not the same. 


When sorting a list of text items having different scripts, first sort the items 
by script, producing sublists. Then within each sublist sort the text items, 
using the International Utilities comparison routine described later in this 
chapter, with the intlForce off and the font in thePort set to one of the fonts 
in the sublist. 


Where performance is critical, such as when you are sorting very large amounts 
of data in memory, it may be advantageous to use a straight ASCII comparison 
instead of the International Utilities comparison routines. In this case, give 
the user a choice of sorting style (quick versus accurate) in a preferences 
dialog. The stored default setting can be determined when localizing the 
application. 
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INTERNATIONAL STRING COMPARISON 


The International Utilities Package lets you compare strings in a way that 
accounts for diacritical marks and other special characters. The sort order 
built into the package may be localized through a routine stored in 
international resource 1. 


The sort order is determined by a ranking of the entire Macintosh character set. 
The ranking can be thought of as a two-dimensional table. Each row of the table 
is a class of characters such as all A's (uppercase and lowercase, with and 
without diacritical marks). The characters are ordered within each row, but this 
ordering is secondary to the order of the rows themselves. For example, given 
that the rows for letters are ordered alphabetically, the following are all true 
under this scheme: 


"A! < "aq! 
and ‘Ab! < ‘ab' 
but 'Ac' > ‘ab' 


Even though 'A' < ‘'a' within the A row, ‘Ac' > ‘'ab' because the order 'c' > 'b' 
takes precedence over the secondary ordering of the ‘a' and the 'A'. In effect, 
the secondary ordering is ignored unless the comparison based on the primary 
ordering yields equality. 


Note: The Pascal relational operators are used here for convenience only. 
String comparison in Pascal yields very different results, since it 
simply follows the ordering of the characters' ASCII codes. 


When the strings being compared are of different lengths, each character in the 
longer string that doesn't correspond to a character in the shorter one compares 
"greater"; thus 'a' < 'ab'. This takes precedence over secondary ordering, so 
‘a' < 'Ab' even though 'A' < ‘a’. 


Besides letting you compare strings as described above, the International 
Utilities Package includes a routine that compares strings for equality without 
regard for secondary ordering. The effect on comparing letters, for example, is 
that diacritical marks are ignored and uppercase and lowercase are not 
distinguished. 


Figure 6 shows the two-dimensional ordering of the character set (from least to 
greatest as you read from top to bottom or left to right). The numbers on the 
left are ASCII codes corresponding to each row; ellipses (...) designate 
sequences of rows of just one character. Some codes do not correspond to rows 
(such as $61 through $7A, because lowercase letters are included in with their 
uppercase equivalents). See the Toolbox Event Manager for a table showing all 
the characters and their ASCII codes. 


Characters combining two letters, as in the $AE row, are called ligatures. As 
shown in Figure 7, they're actually expanded to the corresponding two letters, 
in the following sense: 


¢ Primary ordering: The ligature is equal to the two-character sequence. 
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¢ Secondary ordering: The ligature is greater than the two-character 
sequence. 
$00 = ASCIINUL 


$1F ASCIUS 
$20 space nonbresking space 


$22 “eye” 


aed 
hN 
oO 
S o~ “SP Qrx 


AAAaaaaada a 


letters not shown 
are like "B b" 


Sed 
tb 
Les] 


{ 
| 
} 
$7F ASCII DEL 
+ 


$4E A xe Ch ce (see remarks about ligatures) 


Figure 6. International Character Ordering 
Figure 6—International Character Ordering 
Ligatures are ordered somewhat differently in Germany to accommodate umlauted 


characters (see Figure 7). This is accomplished by means of the routine in 
international resource 1 for localizing the built-in character ordering. In the 
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system resource file for Germany, this routine expands umlauted characters to 
the corresponding two letters (for example, "AE" for A-umlaut). The secondary 
ordering places the umlauted character between the two-character sequence and 
the ligature, if any. Likewise, the German double-s character expands to "ss". 


Built-in ordering: 


HE JE ae 
OE CE oe ce 


Gennan oder: 


AE A zH ae 8 
OE O CE of 6 ce 
a3 fi 

UE U ve it 


Figure 7-Ordering for Special Characters 
Figure 7—Ordering for Special Characters 


In the system resource file for Great Britain, the localization routine in 
international resource 1 orders the pound currency sign between double quote and 
the pound weight sign (see Figure 8). For the United States, France, and Italy, 
the localization routine does nothing. 


$22 Meg eT 
FAS £ 
f2a + 


Figure 6-Special Ordering for Great Britain 
Figure 8-Special Ordering for Great Britain 


Assembly-language note: The null localization routine consists of an 
RTS instruction. 
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SORTING ROUTINES 


Note: The extensions to the International Utilities Package described in this 
section were originally documented in Inside Macintosh, Volume V. As 
such, this information refers to the Macintosh SE and Macintosh II ROMs 
and System file version 4.1 and later. 


eeeClick on the X-Ref button, and refer to Technical Note #178.¢ee 


The international sorting routines handle cases where letters are equal in 
primary ordering but different in secondary ordering (e.g., ‘a' and ‘a'). 

They also handle cases where one character sorts as if it were two (e.g., ‘#' as 
‘ae'). The 'itl2' resource has been added to generalize the sorting process for 
non-Roman scripts. 


a 


This is the process that the International Utilities Package now uses to compare 
two strings: 


e Starting with the first character, it fetches corresponding 
characters from the two strings and compares them. 

e If the characters are identical, the comparison continues. 

e If the characters are not identical, and if one or both is part of a 
secondary ordering (e.g., ‘a' and ‘a'), their primary characters are 
compared. 

¢ If the characters are not identical but their primary characters are 
equal, the comparison continues. 

¢ If neither the original characters nor their primary characters are 
equal, the comparison ends and the ordering of the original characters 
is returned. 

e If the foregoing comparison continues and one string ends before the 
other, then the shorter string is less. 

e If the comparison continues to the end of strings that are the same 
length and if the strings contain no characters that are equal in 
primary ordering but different in secondary ordering, then the strings 
are identical. 

e If the comparison continues to the end of strings that are the same 
length and contain one or more characters that are equal in primary 
ordering but different in secondary ordering, then the first such pair 
of characters is compared by secondary ordering to determine the final 
ordering. 


Note: It is possible to create your own ordering routine, using hook 
routines contained in the 'itl2' resource. For guidance on doing 
this, contact Developer Technical Support. 
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USING THE INTERNATIONAL UTILITIES PACKAGE 


The International Utilities Package is automatically read into memory from the 
system resource file when one of its routines is called. When a routine needs to 
access an international resource, it asks the Resource Manager to read the 
resource into memory. Together, the package and its resources occupy about 2K 
bytes. 


As described in the Operating System Utilities chapter, you can get the date and 
time as a long integer from the GetDateTime procedure. If you need a string 
corresponding to the date or time, you can pass this long integer to the 
IUDateString or IUTimeString procedure in the International Utilities Package. 
These procedures determine the local format from the international resources 
read into memory by the Resource Manager (that is, resource type 'INTL' and 
resource ID 0 or 1). In some situations, you may need the format information to 
come instead from an international resource that you specify by its handle; if 
so, you can use [UDatePString or IUTimePString. This is useful, for example, if 
you want to use an international resource in a document's resource file after 
you've closed that file. 


Applications that use measurements, such as on a ruler for setting margins and 
tabs, can call IUMetric to find out whether to use the metric system. This 
function simply returns the value of the corresponding field in international 
resource 0. To access any other fields in an international resource—say, the 
currency format in international resource 0—call IUGetIntl to get a handle to 
the resource. If you change any of the fields and want to write the changed 
resource to a resource file, the IUSetIntl procedure lets you do this. 


To sort strings, you can use IUCompString or, if you're not dealing with Pascal 
strings, the more general IUMagString. These routines compare two strings and 
give their exact relationship, whether equal, less than, or greater than. 
Subtleties like diacritical marks and case differences are taken into 
consideration, as described above under "International String Comparison". If 
you need to know only whether two strings are equal, and want to ignore the 
subtleties, use IUEqualString (or the more general IUMagIDString) instead. 


Note: The Operating System Utility function EqualString also compares two 
Pascal strings for equality. It's less sophisticated than IUEqualString 
in that it follows ASCII order more strictly; for details, see the 
Operating System Utilities chapter. 
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INTERNATIONAL UTILITIES PACKAGE ROUTINES 


Assembly-language note: The trap macro for the International Utilities 
Package is Pack6. The routine selectors are as 


follows: 
iuDateString .EQU 0 
iuTimeString .EQU 2 
iuMetric .EQU 4 
iuGetIntl .EQU 6 
iuSetIintl .EQU 8 
iuMagString .EQU 10 
iuMagIDString .EQU 12 
iuDatePString .EQU 14 
iuTimePString .EQU 16 


PROCEDURE IUDateString (dateTime: LONGINT; form: DateForm; 
VAR result: Str255); 


Given a date and time as returned by the Operating System Utility procedure 
GetDateTime, IUDateString returns in the result parameter a string that 
represents the corresponding date. The form parameter has the following data 
type: 


TYPE DateForm = (shortDate, LongDate, abbrevDate) ; 


ShortDate requests the short date format, longDate the long date, and abbrevDate 
the abbreviated long date. IUDateString determines the exact format from 
international resource © for the short date or 1 for the long date. See Figure 1 
for examples of the standard formats. 


If the abbreviated long date is requested and the abbreviation length in 
international resource 1 is greater than the actual length of the name being 
abbreviated, IUDateString fills the abbreviation with NUL characters (ASCII code 
0); the abbreviation length should not be greater than 15, the maximum name 
length. 


PROCEDURE IUDatePString (dateTime: LONGINT; form: DateForm; 
VAR result: Str255; intlParam: Handle); 


IUDatePString is the same as IUDateString except that it determines the exact 
format of the date from the resource whose handle is passed in intlParam, 
overriding the resource that would otherwise be used. 


PROCEDURE IUTimeString (dateTime: LONGINT; wantSeconds: BOOLEAN; 
VAR result: Str255); 


Given a date and time as returned by the Operating System Utility procedure 
GetDateTime, IUTimeString returns in the result parameter a string that 
represents the corresponding time of day. If wantSeconds is TRUE, seconds are 
included in the time; otherwise, only the hour and minute are included. 
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IUTimeString determines the time format from international resource 0. See 
Figure 1 for examples of the standard formats. 


PROCEDURE IUTimePString (dateTime: LONGINT; wantSeconds: BOOLEAN; 
VAR result: Str255; intlParam: Handle); 


IUTimePString is the same as IUTimeString except that it determines the time 
format from the resource whose handle is passed in intlParam, overriding the 
resource that would otherwise be used. 


FUNCTION IUMetric : BOOLEAN; 


If international resource 0 specifies that the metric system is to be used, 
IUMetric returns TRUE; otherwise, it returns FALSE. 


FUNCTION IUGetIntl (theID: INTEGER) : Handle; 


IUGetIntl returns a handle to the international resource numbered theID (0 or 
1). It calls the Resource Manager function GetResource('INTL',theID). For 
example, if you want to access individual fields of international resource 0, 
you can do the following: 


VAR myHndl: Handle; 
int®: IntlOHndl; 


myHndl := I[UGetIntl(0); 
intO® := IntlOHndl (myHndl) 


PROCEDURE IUSetIntl (refNum: INTEGER; theID: INTEGER; intlParam: Handle); 


In the resource file having the reference number refNum, IUSetIntl sets the 
international resource numbered theID (0 or 1) to the data specified by 
intlParam. The data may be either an existing resource or data that hasn't yet 
been written to a resource file. IUSetIntl adds the resource to the specified 
file or replaces the resource if it's already there. 


FUNCTION IUCompString (aStr,bStr: Str255) : INTEGER; [Not in ROM] 
IUCompString compares aStr and bStr as described above under "International 


String Comparison", taking both primary and secondary ordering into 
consideration. It returns one of the values listed below. 


Example 
Result Meaning aStr bStr 
-1 aStr is less than bStr "Ab' ‘ab' 
0 aStr equals bStr ‘Ab! ‘Ab! 
1 aStr is greater than bStr "AC' ‘ab' 


Assembly-language note: JIUCompString was created for the convenience 
of Pascal programmers; there's no trap for it. 
It eventually calls IUMagString, which is what 
you should use from assembly language. 


FUNCTION IUMagString (aPtr,bPtr: Ptr; aLen,bLen: INTEGER) : INTEGER; 
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IUMagString is the same as IUCompString (above) except that instead of comparing 
two Pascal strings, it compares the string defined by aPtr and aLen to the 
string defined by bPtr and bLen. The pointer points to the first character of 
the string (any byte in memory, not necessarily word-aligned), and the length 
specifies the number of characters in the string. 


FUNCTION IUEqualString (aStr,bStr: Str255) : INTEGER; [Not in ROM] 


IUEqualString compares aStr and bStr for equality without regard for secondary 
ordering, as described above under "International String Comparison". If the 
strings are equal, it returns 0; otherwise, it returns 1. For example, if the 
strings are 'Rose' and 'rose', IUEqualString considers them equal and returns 0. 


Note: See also EqualString in the Operating System Utilities chapter. 


Assembly-language note: JIUEqualString was created for the convenience of 
Pascal programmers; there's no trap for it. It 
eventually calls IUMagIDString, which is what you 
should use from assembly Language. 


FUNCTION IUMagIDString (aPtr,bPtr: Ptr; aLen,bLen: INTEGER) : INTEGER; 


IUMagIDString is the same as IUEqualString (above) except that instead of 
comparing two Pascal strings, it compares the string defined by aPtr and aLen to 
the string defined by bPtr and bLen. The pointer points to the first character 
of the string (any byte in memory, not necessarily word-aligned), and the length 
specifies the number of characters in the string. 
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SUMMARY OF THE INTERNATIONAL UTILITIES PACKAGE 


Constants 
CONST 
zeroCycle =.7]; {0:00 AM/PM format [Volume V addition] } 


{ Masks for currency format } 


currSymLead = 16; {set if currency symbol leads} 
currNegSym = 32; {set if minus sign for negative} 
currTrailingZ = 64; {set if trailing decimal zeroes} 
currLeadingZ = 128; {set if leading integer zero} 


{ Order of short date elements } 


mdy = 0; {month day year} 
dmy = 1; {day month year} 
ymd = 2; {year month day} 
MYD = 3; {month, day, year [Volume V addition] } 
DYM = 4; {day, year, month [Volume V addition] } 
YDM Sib f{year, day, month [Volume V addition] } 


{ Masks for short date format } 


dayLdingZ = 32; {set if leading zero for day} 
mntLdingZ = 64; {set if leading zero for month} 
century = 128; {set if century included} 


{ Order of long date elements } 


LongDay = 0; {day of the month [Volume V addition] } 
LongWeek = 1° {day of the week [Volume V addition] } 
LongMonth = 2° {month of the year [Volume V addition] } 
longYear = 3; {year [Volume V addition] } 


{ Suppression of date elements } 


supDay = 1; {suppress day of month [Volume V addition] } 
supWeek = 2: {suppress day of week [Volume V addition] } 
supMonth = 4; {suppress month [Volume V addition]} 
supYear = 8; {suppress year [Volume V addition] } 


{ Masks for time format } 


secLeadingZ = 32; {set if leading zero for seconds} 
minLeadingZ = 64; {set if leading zero for minutes} 
hrLeadingZ = 128; {set if leading zero for hours} 


{ High-order byte of version information } 
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verUS = 0; 

verFrance = 1; 

verBritain =<2" 

verGermany = 3; 

verItaly = 4; 

verNetherlands = 5; 

verBelgiumLux = 6; 

verSweden = 7; 

verSpain = 8; 

verDenmark = 9; 

verPortugal = 10; 

verFrCanada = 11; 

verNorway = 12; 

verIsrael = 13; 

verJapan = 14; 

verAustralia = 15; 

verArabia = 16; 

verFinland = 17; 

verFrSwiss = 18; 

verGrSwiss = 19; 

verGreece = 20; 

vericeland = 21; 

verMalta = 22; 

verCyprus = 23; 

verTurkey = 24; 

verYugoslavia = 25; 

Data Types 
TYPE 

IntlOHndl = *IntlOPtr; 

IntlOPtr = *“IntlORec; 

IntlORec = PACKED RECORD 
decimalPt: CHAR; {decimal point character} 
thousSep: CHAR; {thousands separator} 
listSep: CHAR; {list separator} 
currSym1: CHAR; {currency symbol} 
currSym2: CHAR; 
currSym3: CHAR; 
currFmt: Byte; {currency format} 
dateOrder: Byte; {order of short date elements} 
shrtDateFmt: Byte; {short date format} 
dateSep: CHAR; {date separator} 
timeCycle: Byte; {0 if 24-hour cycle, 255 if 12-hour} 
timeFmt: Byte; {time format} 
mornStr: PACKED ARRAY[1..4] OF CHAR; 


{trailing string for first } 
{ 12-hour cycle} 

eveStr: PACKED ARRAY[1..4] OF CHAR; 
{trailing string for last } 
{ 12-hour cycle} 


timeSep: CHAR; {time separator} 
timelSuff: CHAR; {trailing string for 24-hour cycle} 
time2Suff: CHAR; 
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time3Suff: CHAR; 
time4Suff: CHAR; 
time5Suff: CHAR; 
time6Suf f: CHAR; 
time7Suff: CHAR; 
time8Suff: CHAR; 
metricSys: Byte; {255 if metric, 0 if not} 
intlOVers: INTEGER {version information} 
END; 
IntllHndl = *Intl1Ptr; 
IntllPtr = *Intl1Rec; 
IntllRec = PACKED RECORD 
days: ARRAY[1..7] OF STRING[15]; {day names} 
months: ARRAY[1..12] OF STRING[15]; {month names} 
SuppressDay: Byte; {0 for day name, 255 for none} 
LngDateFmt: Byte; {order of long date elements} 
dayLeadingO: Byte; {255 for leading 0 in day number} 
abbrLen: Byte; {length for abbreviating names} 
ste: PACKED ARRAY[1..4] OF CHAR; {strings } 
stl: PACKED ARRAY[1..4] OF CHAR; { for } 
st2: PACKED ARRAY[1..4] OF CHAR; { long } 
st3: PACKED ARRAY[1..4] OF CHAR; { date } 
st4: PACKED ARRAY[1..4] OF CHAR; { format} 
intllVers: INTEGER; {version information} 
localRtn: INTEGER {routine for localizing string } 
{ comparison; actually may be } 
{ longer than one integer} 
END; 
DateForm = (shortDate, LongDate, abbrevDate) ; 
Routines 
PROCEDURE IUDateString (dateTime: LONGINT; form: DateForm; 
VAR result: Str255); 
PROCEDURE IUDatePString (dateTime: LONGINT; form: DateForm; 
VAR result: Str255; intlParam: Handle); 
PROCEDURE IUTimeString (dateTime: LONGINT; wantSeconds: BOOLEAN; 
VAR result: Str255); 
PROCEDURE IUTimePString (dateTime: LONGINT; wantSeconds: (BOOLEAN; 
VAR result: Str255;intlParam: Handle); 
FUNCTION IUMetric : BOOLEAN; 
FUNCTION IUGetIntl (theID: INTEGER) Handle; 
PROCEDURE IUSetIntl (refNum: INTEGER; theID: INTEGER; 
intlParam: Handle); 
FUNCTION IUCompString (aStr,bStr: Str255) INTEGER; [Not in ROM] 
FUNCTION JIUMagString (aPtr,bPtr: Ptr; aLen,bLen: INTEGER) INTEGER; 
FUNCTION JIUEqualString (aStr,bStr: Str255) INTEGER; [Not in ROM] 
FUNCTION JIUMagIDString (aPtr,bPtr: Ptr; aLen,bLen: INTEGER) INTEGER; 


Assembly-Language Information 
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Constants 
zeroCycle EQU 1 ;use 0:00 AM/PM format [Volume V addition] 


; Masks for currency format 


currSymLead .EQU 16 ;set if currency symbol leads 
currNegSym .EQU 32 ;set if minus sign for negative 
currTrailingZ .EQU 64 ;set if trailing decimal zeroes 
currLeadingZ .EQU 128 ;set if leading integer zero 


: Order of short date elements 


mdy .EQU 0 ;month day year 
dmy . EQU 1 ;day month year 
ymd . EQU 2 ;year month day 
MYD EQU 3 ;use month, year, day [Volume V addition] 
DYM EQU 4 ;use day, year, month [Volume V addition] 
YDM EQU 5 ;use year, day, month [Volume V addition] 


: Masks for short date format 


dayLdingZ .EQU 32 ;set if leading zero for day 
mntLdingZ .EQU 64 ;set if leading zero for month 
century .EQU 128 ;set if century included 


; Order of long date elements 


LongDay EQU 0 ;day of month [Volume V addition] 
LongwWeek EQU 1 ;day of week [Volume V addition] 
LongMonth EQU 2 ;month of year [Volume V addition] 
longYear EQU 3 ;year [Volume V addition] 


; Supression of date elements 


supDay EQU 0 ;suppress day of month [Volume V addition] 
supWeek EQU 2 ;suppress day of week [Volume V addition] 
supMonth EQU 4 ;suppress month [Volume V addition] 
supYear EQU 8 ;suppress year [Volume V addition] 


» Masks for time format 


secLeadingZ . EQU 32 ;set if leading zero for seconds 
minLeadingZ .EQU 64 ;set if leading zero for minutes 
hrLeadingZ .EQU 128 ;set if leading zero for hours 


; High-order byte of version information 


verUS . EQU 0 
verFrance . EQU 1 
verBritain . EQU 2 
verGermany .EQU 3 
verItaly .EQU 4 
verNetherlands.EQU 5 
verBelgiumLux .EQU 6 


@ SpInside Macintosh ¢« Version 1.0 * November 1989 * Apple Computer 
THE INTERNATIONAL UTILITIES PACKAGE ¢ 25 of 28 


verSweden 
verSpain 
verDenmark 


verPortugal 
verFrCanada 


verNorway 
verIsrael 
verJapan 


verAustralia 


verArabia 
verFinland 
verFrSwiss 
verGrSwiss 
verGreece 
vericeland 
verMalta 
verCyprus 
verTurkey 


verYugoslavia .EQU 


. EQU 7 

. EQU 8 

. EQU 9 

. EQU 10 
. EQU 11 
. EQU 12 
. EQU 13 
. EQU 14 
. EQU 15 
. EQU 16 
. EQU 17 
. EQU 18 
. EQU 19 
. EQU 20 
. EQU 21 
. EQU 22 
. EQU 23 
. EQU 24 


; Date form for IUDateString and IUDatePString 


shortDate 
longDate 
abbrevDate 


.EQU 0 ;short form of date 
.EQU 1 ; long form of date 
. EQU 2 ;abbreviated long form 


» Routine selectors 


iuDateString .EQU 0 
iuTimeString .EQU 2 
iuMetric .EQU 4 
iuGetIntl .EQU 6 
iuSetIintl .EQU 8 
iuMagString .EQU 10 
iuMagIDString .EQU 12 
iuDatePString .EQU 14 
iuTimePString .EQU 16 


International Resource 0 Data Structure 


decimalPt 
thousSep 
listSep 
currsym 
currFmt 
dateOrder 


shrtDateFmt 


dateSep 
timeCycle 
timeFmt 
mornStr 
eveStr 
timeSep 
timeSuf f 
metricSys 
intlOVers 


Decimal point character (byte) 

Thousands separator (byte) 

List separator (byte) 

Currency symbol (3 bytes) 

Currency format (byte) 

Order of short date elements (byte) 

Short date format (byte) 

Date separator (byte) 

0 if 24-hour cycle, 255 if 12-hour (byte) 
Time format (byte) 

Trailing string for first 12-hour cycle (long) 
Trailing string for last 12-hour cycle (long) 
Time separator (byte) 

Trailing string for 24-hour cycle (8 bytes) 
255 if metric, 0 if not (byte) 

Version information (word) 
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International Resource 1 Data Structure 


days Day names (112 bytes) 

months Month names (192 bytes) 

SuppressDay 0 for day name, 255 for none (byte) 
lngDateFmt Order of long date elements (byte) 
dayLeading® 255 for leading 0 in day number (byte) 


abbrLen Length for abbreviating names (byte) 
std Strings for long date format (longs) 
stl 

st2 

st3 

st4 

intll1Vers Version information (word) 

localRtn Comparison localization routine 


Trap Macro Name 


_Pack6 
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Further Reference: 


Resource Manager 
Package Manager 
System Resource File 
OS Utilities 


Script Manager 
Technical Note #153, Changes in International Utilities and Resources 


Technical Note #178, Modifying the Standard String Comparison 
Technical Note #242, Fonts and the Script Manager 


END OF DOCUMENT 
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